home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / Eval.3 < prev    next >
Text File  |  1994-09-20  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tcl_Eval(3)          Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval  -  exe-
  12.      cute Tcl commands
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      int
  18.      Tcl_Eval(_i_n_t_e_r_p, _c_m_d)                                         |
  19.  
  20.      int
  21.      Tcl_VarEval(_i_n_t_e_r_p, _s_t_r_i_n_g, _s_t_r_i_n_g, ... (char *) NULL)
  22.  
  23.      int
  24.      Tcl_EvalFile(_i_n_t_e_r_p, _f_i_l_e_N_a_m_e)
  25.  
  26.      int
  27.      Tcl_GlobalEval(_i_n_t_e_r_p, _c_m_d)
  28.  
  29. ARGUMENTS
  30.      Tcl_Interp   *_i_n_t_e_r_p      (in)      Interpreter in which  to
  31.                                          execute   the   command.
  32.                                          String  result  will  be
  33.                                          stored     in    _i_n_t_e_r_p-
  34.                                          >_r_e_s_u_l_t.
  35.  
  36.      char         *_c_m_d         (in)      Command (or sequence  of
  37.                                          commands)   to  execute.
  38.                                          Must  be   in   writable
  39.                                          memory  (Tcl_Eval  makes
  40.                                          temporary  modifications
  41.                                          to the command).
  42.  
  43.      char         *_s_t_r_i_n_g      (in)      String forming  part  of
  44.                                          Tcl command.
  45.  
  46.      char         *_f_i_l_e_N_a_m_e    (in)      Name of file  containing
  47.                                          Tcl command string.
  48. _________________________________________________________________
  49.  
  50.  
  51. DESCRIPTION
  52.      All four of these procedures execute Tcl commands.  Tcl_Eval
  53.      is the core procedure:  it parses commands from _c_m_d and exe-
  54.      cutes them in order until  either  an  error  occurs  or  it  |
  55.      reaches  the  end  of  the  string.   The  return value from
  56.      Tcl_Eval is one of the Tcl return codes  TCL_OK,  TCL_ERROR,
  57.      TCL_RETURN,  TCL_BREAK,  or TCL_CONTINUE, and _i_n_t_e_r_p->_r_e_s_u_l_t
  58.      will point to a string with additional  information  (result
  59.      value   or   error   message).    This   return  information
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_Eval(3)          Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74.      corresponds to the last command executed from _c_m_d.
  75.  
  76.      Tcl_VarEval takes any number  of  string  arguments  of  any
  77.      length,  concatenates  them into a single string, then calls
  78.      Tcl_Eval to execute  that  string  as  a  Tcl  command.   It
  79.      returns  the result of the command and also modifies _i_n_t_e_r_p-
  80.      >_r_e_s_u_l_t in the usual fashion for  Tcl  commands.   The  last
  81.      argument  to Tcl_VarEval must be NULL to indicate the end of
  82.      arguments.
  83.  
  84.      Tcl_EvalFile reads the file given by _f_i_l_e_N_a_m_e and  evaluates
  85.      its  contents  as  a  Tcl  command  by calling Tcl_Eval.  It
  86.      returns a standard Tcl result that reflects  the  result  of
  87.      evaluating  the  file.   If the file couldn't be read then a
  88.      Tcl error is returned to describe why the file  couldn't  be
  89.      read.
  90.  
  91.      Tcl_GlobalEval  is  similar  to  Tcl_Eval  except  that   it
  92.      processes  the command at global level.  This means that the
  93.      variable context for the command consists  of  global  vari-
  94.      ables  only  (it  ignores any Tcl procedure that is active).
  95.      This produces an effect similar to the Tcl command ``uplevel
  96.      0''.
  97.  
  98.      During the processing of a Tcl command it is legal  to  make
  99.      nested  calls to evaluate other commands (this is how condi-
  100.      tionals, loops, and procedures are implemented).  If a  code
  101.      other than TCL_OK is returned from a nested Tcl_Eval invoca-
  102.      tion, then the caller should  normally  return  immediately,
  103.      passing  that same return code back to its caller, and so on
  104.      until the top-level application is reached.  A few commands,
  105.      like   for,  will  check  for  certain  return  codes,  like
  106.      TCL_BREAK  and  TCL_CONTINUE,  and  process  them  specially
  107.      without returning.
  108.  
  109.      Tcl_Eval keeps track of how many nested Tcl_Eval invocations
  110.      are  in  progress  for  _i_n_t_e_r_p.   If  a  code of TCL_RETURN,
  111.      TCL_BREAK, or TCL_CONTINUE is about to be returned from  the
  112.      topmost  Tcl_Eval  invocation for _i_n_t_e_r_p, then Tcl_Eval con-
  113.      verts the return code to TCL_ERROR and  sets  _i_n_t_e_r_p->_r_e_s_u_l_t
  114.      to  point  to  an  error message indicating that the return,
  115.      break, or continue command was invoked in  an  inappropriate
  116.      place.   This means that top-level applications should never
  117.      see a  return  code  from  Tcl_Eval  other  then  TCL_OK  or
  118.      TCL_ERROR.
  119.  
  120.  
  121. KEYWORDS
  122.      command, execute, file, global, interpreter, variable
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.